Bulk Modify Subscriber Balance

Bulk Modify Subscriber Balance API is used to add or deduct money from/to a subscriber postpaid balance of multiple subscribers in a single call.

This function does not change the RATE type offer limit values.

HTTP URL

 

PUT

api/v2/bulk/subscriber/balance

Eligibility

The Requestor is eligible to add or deduct money to/from his direct sub-accounts’ subscribers only. It is not allowed to perform these changes neither on its own subscribers nor any other sub-accounts level subscribers.

API Request

Request Structure

Parameter Type M/O/CM Description
Bulk

Object

 M

Array of main request body object.

Bulk data objects

Element Type M/O/CM Description
subscriberIdentifiers

Object

 M Subscriber unique keys object, defines the search criteria.
content

Object

 M Main elements container object.

subscriberidentifiers data objects

Element Type M/O/CM Description
type String M Define the search criteria. ENUMs: IMSI, ICCID, MSISDN, IMEI
value String M Type value. IMSI or ICCID or MSISDN or IMEI number.

Content data objects

Parameter Type M/O/CM Description
amount Decimal M Add or deduct money to/from the subscriber’s postpaid balance. Sending a positive value will perform a DEBIT action (deduct money from the balance). Sending a negative value will perform a CREDIT action (add money to the balance).
currency String M Monetary currency. e.g., USD, GBP, EUR
quantity Numeric O Quantity represents how many adjustments are needed. For example, amount 10, currency “USD” with quantity 3 will result in an adjustment of $30 (amount × quantity). Must be a positive number. Default if not sent is 1.
referenceTime DateTime O Self-recorded timestamp. Note: It is not the actual transaction date and time. It is not possible to populate a date for future execution. The adjustment is executed immediately when the API is sent. Default if not sent – now().
externalTransactionId String O External Reference identifier. Relevant if a search for a transaction is required in reports or extractions.
description String O Adjustment description. Free text.
transactionType String O Type of transaction. Currently supports manual adjustments only. ENUM valid values: MANUAL_ADJUSTMENT. Default if not sent: MANUAL_ADJUSTMENT.
reason String O Reason for the transaction per type. Manual adjustment ENUM valid values: GENERAL, DISCOUNT, RATES_ADJUSTMENTS, REFUND, CREDIT, SHIPMENT_COST, ORDER_COST, DEBT. Default if not sent: GENERAL.

Allowance data objects

Element Type M/O/CM Description
currency String M Allowance: SMS: (Number of) SMSs | Data: KB, MB, GB
value Decimal M Balance amount

API Response

Response Structure

Parameter Type M/O/CM Description
bulk Object M Array of main response body object.
pageable Object O Paging information object displayed when an API call was successful. For a failure, it will be empty.

Bulk data objects

Parameter Type M/O/CM Description
errorCode

String

 O Failure code.
errorMessage String O Failure message.
messageId UUID CM Request instance ID. To be used by external systems to query the call (operation) status: In progress Successful Failed. Displayed when an API call was successful. For a failure, it will be empty.
subscriberIdentifiers Object M Subscriber unique keys object, defines the search criteria.
content Object O Main response body object that reflects a single node of the original request.

subscriberidentifiers data objects

Parameter

Type

M/O/CM

Description
type String M

Define the search criteria.

Valid Types: ENUMs: IMSI, ICCID, MSISDN, IMEI
value String M Type value. IMSI or ICCID or MSISDN or IMEI number.

Content data objects

Parameter Type M/O/CM Description
amount Decimal M Add or deduct money to/from the subscriber’s postpaid balance. Sending a positive value will perform a DEBIT action (deduct money from the balance). Sending a negative value will perform a CREDIT action (add money to the balance).
currency String M Monetary currency. e.g., USD, GBP, EUR
quantity Numeric O Quantity represents how many adjustments were requested. For example, amount 10, currency “USD”, with quantity 3 results in an adjustment of $30 (amount × quantity).
referenceTime DateTime O Self-recorded timestamp. Note: It is not the actual transaction date and time. It is not possible to populate a date for future execution. The adjustment is executed immediately when the API is sent.
externalTransactionId String O External Reference identifier. Relevant if a search for a transaction is required in reports or extractions.
description String O Adjustment description. Free text.
transactionType String O Type of transaction. Currently supports manual adjustments only. ENUM valid values: MANUAL_ADJUSTMENT.
reason String O Reason for the transaction per type. Manual adjustment ENUM valid values: GENERAL, DISCOUNT, RATES_ADJUSTMENTS, REFUND, CREDIT, SHIPMENT_COST, ORDER_COST, DEBT.

Pageable data objects

Element Type M/O/CM Description
page Numeric M Page number
size Numeric M Page size. Number of requested elements per page
totalPages Numeric M Total amount of available pages per requested page size
totalElements Numeric M Total amount of retrieved elements

Error Codes

In addition to the general success and failure codes, the following error codes are possible.

Code Message
GLOBAL_1001 Service unavailable. Please try again
SUBSCRIBER_1002 Subscriber does not exist

Examples

Request Body

Copy 
{
  "bulk": [
    {
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961859"
      },
      "content": {
        "amount": -25,
        "currency": "USD",
        "quantity": 1,
        "referenceTime": "",
        "externalTransactionId": "",
        "description": "Applying three months discount",
        "transactionType": "MANUAL_ADJUSTMENT",
        "reason": "DISCOUNT"
      }
    },
    {
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000034535"
      },
      "content": {
        "amount": 10,
        "currency": "GBP",
        "quantity": 1,
        "referenceTime": "",
        "externalTransactionId": "",
        "description": "Collecting debt",
        "transactionType": "MANUAL_ADJUSTMENT",
        "reason": "DEBT"
      }
    }
  ] 
}

Response Body: Full Success (ACK)

Copy 
{
  "bulk": [
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "ff74dca6-8e7f-4b85-a42b-13860913b370",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961963"
      },
      "content": {
        "amount": -25,
        "currency": "USD",
        "quantity": 1,
        "referenceTime": "",
        "externalTransactionId": "",
        "description": "Applying three months discount",
        "transactionType": "MANUAL_ADJUSTMENT",
        "reason": "DISCOUNT"
      }
    },
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "7e74dce6-8eef-4c86-a4bb-1a860913c271",
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000035687"
      },
      "content": {
        "amount": 10,
        "currency": "GBP",
        "quantity": 1,
        "referenceTime": "",
        "externalTransactionId": "",
        "description": "Collecting debt",
        "transactionType": "MANUAL_ADJUSTMENT",
        "reason": "DEBT"
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}

Response Body: Includes Failure(s) (NAK)

Copy 
{
  "bulk": [
    {
      "errorCode": "SUBSCRIBER_1002",
      "errorMessage": "Subscriber does not exist",
      "requestId": "",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961963"
      },
      "content": {
        "amount": -25,
        "currency": "USD",
        "quantity": 1,
        "referenceTime": "",
        "externalTransactionId": "",
        "description": "Applying three months discount",
        "transactionType": "MANUAL_ADJUSTMENT",
        "reason": "DISCOUNT"
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}